Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-02/tprint.zip/PRINTER.DOC

Text File | 1991-05-21 | 50KB | 731 lines

                             DOCUMENTATION FOR TURBO PASCAL PRINTER UNITS

        These units are for use in Turbo Pascal Windows Programs.  They are shareware.  You may use
these units in any non-commercial products freely.  You may copy the programs and the documentation
and distribute them freely.  If these units are to be incorporated into a commercial product, or if you wish
source on disk, please send $25.00 to OptiCom, Inc, Box 16-1127, Miami, FL 33116.  Our phone
number is [phone], and our CompuServe ID is 71250,71.  If you register the product, I will send
you irregular updates of these objects as I improve them.

        These objects, all source code and the contents of this document are copyright (c) 1991 OptiCom,
Inc.  We would sincerely welcome any comments/criticism/ideas you might have about these objects.

        The idea for these objects and the information in this document came from several sources.  The
objects themselves are loosely based on the printer classes contained in the Actor Development
Environment, an excellent product of the Whitewater Group.  Other material came from Charles Petzold's
Programming Windows, the Microsoft SDK, the Turbo Windows Manuals, Compuserve and several
friends and associates.

Files on this disk:
        pDevice.pas            Formal printer object, tPrnDevice.
        printer.pas            Printer Object, tPrinter.
        repPrn.pas             example of a report printer derived from the printer class.
        testPrn1.pas           example file printer program, using the tPrinter object.
        testPrn2.pas           example file printer program, using the reportPrinter object.
        test.res               resource file
        prt.res                resurce file
        printer.doc            This document


GENERAL OVERVIEW
        These objects are designed to provide an interface between a printer and an application running
under Windows.  The structure of these objects is such that you should not have to modify them to add
functionality or change their behavior.  You should create descendants of the objects to add additional
features.  An example of this is the ReportPrinter object, in the file RepPrn.pas.  The reportPrinter object
adds several features to the printer unit to handle headings and page size.  Having learned the basics of
OOP in the Actor environment, I have come to appreciate the advantages of adhering as strictly as
possible to the principles of OOP.  The Actor environment is pure OOP.  That means that everything
(and I mean everything!) is an object.  The main advantage of OOP programming is the ease of
modifying and extending the objects that you create.  I hope these objects will prove to be good examples
of this type of programming.

        These objects have been written with the OOP philosophy in mind.  There is no access to the
instance variables of an object outside that object's scope.  All access to instance variables is through the
methods of the object.  Modifications to be made to the objects are made through descendants, not by
modifying the code of the object.  This is illustrated by the ReportPrinter object.

        This document is divided into several sections.  The first discusses the relationship between
Windows and the printer.  It covers, in a general manner, the calls to Windows contained in the objects.
I have tried to provide enough information to make clear what I am doing in each object, and so that the
objects can be extended to suit your own needs.  The other sections discuss the objects themselves and
the sample programs.  Each object section contains an explanation of the declared types in the unit, the
object's instance variables and methods, and a bit about what the object is supposed to do.  The sections
on the sample programs discuss the nature of the programs, and how they use the objects to print.

PRINTING IN WINDOWS
        It used to be that all you had to do to print something was USE the printer, and let fly.  With
some well placed WriteLn statements and judicious spacing, you could produce reasonable output.  Not
any more.  Under Windows, printing requires almost as much programming as some small applications!

        To a Windows application, sending output to a printer is not much different than sending output
to a window.  The application actually sends its output to Windows, and Windows handles the mechanism
of getting it where it is supposed to go.  In general, printing under Windows requires the following steps:
        1.      The application must retrieve information about the current printer from the WIN.INI file.
        2.      The application must create a device context (a handle) for the printer.
        3.      Output is sent to the device context.
        4.      The application communicates with the printer device driver using escape codes.
        5.      Windows activates the print spooler to manage the print job.

        In addition to these basic steps, an application can also display a dialog box to allow a user to
cancel a print job that is being spooled.  This requires the instantiation of an Abort procedure to notify
windows about the status of the print job.

        Windows' management of each print job revolves around the concept of a document.  You can
think of each, complete print job as a document.  This applies no matter how large the output will be.
Each time a new print job is started, that print job is one document.  Since it is possible that more that
one document may be printing at the same time, each individual print job must be kept separate from any
other print job to avoid mixing them up during output.  The application must notify Windows when a
document is going to start. When printing has finished, the application must notify Windows that the
document has ended.  This notification is done using escape calls.

        In the following section, some of the concepts introduced above will be discussed in greater
detail.

ABORT PROCEDURE:  An abort procedure is known as a callback function.  It is a function in an
application that is called by Windows during a print job.  The function returns a boolean value indicating
whether the user has canceled the print job.  During normal processing, messages sent to the abort
function are translated and dispatched back to Windows.  As long as the print job is not canceled, the
function returns a TRUE value to Windows.  If the print job is canceled, the function returns FALSE,
letting Windows know the job was canceled.

        In order to implement an abort procedure, it is necessary to provide a dialog box and an abort
function.  The dialog box generally contains a brief message ('Sending job to spooler...') and a cancel
button.  Pressing the cancel button should set a variable accessible to the abort function to FALSE.  The
abort procedure must be declared as a EXPORTed function, and must return a boolean value.  This is
done in the AbortProc method of the printer object.  The abort function may not be a method of an
object, since object methods may not be exported.  This also means that the print dialog may not be
contained in an instance variable of an object, since the Abort procedure would not have access to it.
Finally, the variable set by the Cancel method of the print dialog must be global to the unit in which these
two items are declared.  Again, the process necessary for creating an abort mechanism may be seen in
the Printer.pas file.

        The next step is to notify Windows of the existence of the abort function.  This is done by
sending the SETABORTPROC escape code to Windows, with a far pointer to the abort function as a
parameter.  This pointer is obtained through the MakeProcInstance method.  MakeProcInstance creates
a far pointer that is bound to the data segment of the instance of the application that contains the abort
function.  This is so that when Windows calls the abort function, it uses data in the current instance.  The
application instance refers to the instance handle of the current application.  A handle is a number that
uniquely identifies a program running under Windows.  Since multiple instances of a program share code,
it is necessary for Windows to keep track of who is doing what.  The call to MakeProcInstance returns
a tFarPointer which is then used in the SetAbortProc escape call.   The SetAbortProc escape call passes
the pointer to the abort function to Windows.

        If an application does not set an abort procedure, it is quite likely that any errors will cause the
program to crash.  One common error is a lack of disk space for spooling.  In the abort procedure, the
application can decide whether to wait for some disk space to be freed, or to cancel the print job.  If an
print job terminates abnormally, or if it is canceled, the GDI automatically cancels the print job.  In this
case, the application should not attempt to end the print job using escape calls.

        Both the abort procedure and the print dialog box must be instantiated prior to issuing the
STARTDOC escape call to create the document.

DEVICE CONTEXT: When an application wants to use a device, it must obtain a handle for that device
from Windows.  This handle is known as the device context.  Through the device context, an application
has access to various devices attached to the computer.  The device context is actually a data structure
maintained by the GDI, containing information about the particular device to which it belongs.  For
example, when output is sent to the printer, the GDI uses the information contained in this data structure
to properly format the output.  A device context works very much like a file in a Pascal program.  Once
you have assigned a file name to a file variable, all access to the file passes through the file variable.
In a Windows program, all access to the device must 'pass through' the device context handle.

Device Mode:  The device mode function is part of the printer device driver.  These drivers are supplied
by the manufacturer and distributed with Windows.  When you call DeviceMode, you are calling a
routine in a DLL.  The deviceMode call is responsible for displaying the printer dialog box, allowing a
user to change the printer parameters.  The name of the function in a driver written for Windows 3 is
ExtDeviceMode.   In drivers for earlier versions of Windows, the function is DeviceMode.  There are
several differences between these two functions.  The most important one is that in the DeviceMode call,
any changes to the device parameters are reflected in the WIN.INI file.  These changes will affect all
current and future sessions of Windows.  In the ExtDeviceMode procedure, the programmer has the
option to make the changes permanent, or to maintain them for the current session only.

ESCAPE CALLS:  Escape calls allow an application to communicate with a printer device driver.  The
escape sequences contain commands and information for the driver.  They can also be used to obtain
device-specific information.   There are quite a number of escape codes that can be used (57, I believe).
These are listed in the Turbo Windows Reference guide under Printer Escape Codes.

GDI (Graphics Device Interface): The GDI is a programming language that acts as an interface between
an application, the printer device driver and the print manager.   An application does not have to know
anything about the devices with which it will communicate.  As long as the application uses the GDI to
access the devices, all of the output functions will be handled by Windows.  This is known as device-
independence.  As you will see, close communication is necessary between an application, Windows and
the printer driver to print a document.

WIN.INI file:  The WIN.INI file plays an important part in the printing process.  In the method
GetPrinterParms, this file is queried to obtain information about the current printer.  Information in the
WIN.INI file is stored under application name and key name headings. Printer information is contained
under the application name '[windows]' and the key name 'device'.  The key name is followed by the
currently selected printer, the name of it's device driver, and the port to which the printer is connected.
For example, a typical device keyword might look like this:

                                 Device=IBM Proprinters,PROPRINT,LPT1:

        This tells us that the currently selected printer is an IBM Proprinter, the driver is
PROPRINT.DRV, and the printer is connected to LPT1. The settings in this file can be modified by the
DeviceMode call to the printer device driver.  It is also possible, using the ClearEnv method, to force
a device to read the WIN.INI file to obtain the current printer parameters.


===============================================
                                       PRINTER OBJECT REFERENCE

tPrnDevice, Contained in file pDevice.Pas

INSTANCE VARIABLES

hPrintDC        Holds the printer device context.  This variable is instantiated by the DCcreated method.

hWindow         Contains the handle to the parent window from which the printer object was created.
                This variable is instantiated by the Init method, using a value passed from the application.

docName         The name of the document that is being printed.  This variable is instantiated in the
                BeginDoc method.  The document name is used with the STARTDOC escape call to
                uniquely identify the document being printed.  This allows the print manager to manage
                separate print jobs, without their interfering with one another.  When the print manager
                is active, this name appears on the status line for the selected printer.

Device          The name of the printer. This is obtained through a call to getPrinterParms, which
                retrieves the information from the WIN.INI file

Driver          The name of the device driver associated with the device.  This information is also
                obtained through the getPrinterParms call

dMode           a tDevMode data structure.  Although it is not used extensively in these objects,  this
                structure holds a great deal of information about the printer and device driver.  It is used
                by DeviceCapabilities and by the getExtDeviceMode to hold information about a printer
                device driver.

noSpooler       A boolean variable that is set in the GetPrinterParms method, based on the value for
                spooler in the WIN.INI file.  It indicates whether the spooler is active or not.

prnPort         The port to which the object will print.  This information is obtained from the WIN.INI
                file through a call to getPrinterParms.


TYPES

devArray        An 80 character string used in the unit to hold various values.

prnErrors       Enumerated type defining the different errors that can occur during the printing process.
                These are used as parameters when calling the PrnError method.

pPrnDevice      A pointer to the tPrnDevice Object.

tPrnDevice      The formal printer object.  You should not create an instance of this class.  Instantiate
                tPrinter instead.

tGetDevMode     This is a template for a windows function call to display the device driver dialog box for
                drivers not written for windows 3.0.

tGetExtDevMode         This is a template for a windows function call to display the device driver dialog
                box for device drivers written for windows 3.0.



METHODS

AbortPrn        Aborts the current print job.

BeginDoc        Sends the STARTDOC escape call to windows to indicate the start of a document.  This
                is an important call. Included in the Escape call is the name of the document to be
                printed.  This name is used by the GDI to identify a unique print job, and prevents
                documents longer than one page from being mixed in with other documents.  The job
                name appears in the print manager list of jobs.  The STARTDOC call should always be
                paired with an ENDDOC or ABORTDOC escape call.

CallEscape      Sends an escape code to the GDI, using passed parameters. The syntax of an Escape call
                is:
                       Escape(DC: hDC; Escape, Count: Integer; InData, OutData: Pointer): Integer

                where DC is the selected device context, Escape is the escape code, count is the number
                of bytes in InData, and outData is the data structure to receive data from the escape call,
                if requested.  The function returns an integer value that is positive if the escape call was
                successful, zero if escape is not implemented, and negative if an error occurred.  This
                method centralizes the escape calls to allow errors resulting from the calls to be handled
                from one location.  Most errors occur on a NewFrame boundary, which signifies the end
                of a page.

ClearEnv        Clears the device's environment.  This forces the printer driver to read the current printer
                settings from the WIN.INI file.

DCcreated       Creates a device context for the printer by calling the CreateDC method.   CreateDC
                returns a word value greater than 0 if the call was successful.

DeleteContext   Deletes the device context created for the printer.

DeviceName      Returns the value of the Device instance variable.

DocAbort        Sends the ABORTDOC escape code.  This code terminates the current job and erases
                everything the application has written to the device since the last ENDDOC code.  This
                code is normally used to terminate print jobs that have not implemented an abort
                procedure, or those that have not reached their first NewFrame escape call.  If a print
                job terminates due to cancellation or an error, this call should not be used.  The GDI
                automatically terminates print jobs under these circumstances.  If the application has
                created a cancellation dialog, the ABORTDOC code must be sent before the dialog box
                is destroyed, and before freeing an abort procedure-instance.

Done            Destructor method.  Calls the parent (tObject) destructor.

DoNewFrame      Sends the NEWFRAME escape code to Windows. This code lets the printer know that
                the application has finished writing to a page.  It causes a form feed to be issued.  The
                NEWFRAME call restores the default values of the device context.  If a font other than
                the default font has been selected, that font must be reselected after the NEWFRAME
                Escape.

DraftModeOff    Turns the printer draft mode off by sending the DRAFTMODE escape code.  This
                method illustrates the use of the InData structure, sending a word value indicating the
                desired state of the draft mode.  The value is passed in the high portion of the word. A
                value of 0 turns draft mode off, 01 turns it on. The draft mode of the printer can only
                be changed at page boundaries, such as after a NEWFRAME escape call.

DraftModeOn     Turns the printer draft mode on by sending the DRAFTMODE escape code.  This
                method illustrates the use of the InData structure, sending a word value indicating the
                desired state of the draft mode.  The value is passed in the high portion of the word.  A
                value of 0 turns draft mode off, 01 turns it on.  Since the value is passed in the high
                portion of the word, the value passed is 1000.  In the method draftModeOff, the passed
                value is zero.  The draft mode of the printer can only be changed at page boundaries,
                such as after a NEWFRAME escape call.

DriverName      Returns the value of the Driver instance variable.

EndDocument     Sends the ENDDOC Escape code to Windows.  This signals that the current document
                has completed. If the print job has terminated abnormally, this method should not be
                called.  In cases of abnormal termination, the GDI terminates the operation.  If the
                application displays a print cancel dialog, the ENDDOC code must be sent before the
                dialog box is destroyed, and before freeing the procedure instance of an abort procedure.
                The ENDDOC or ABORTDOC escape calls should always be paired with the
                STARTDOC escape call.

EndOfFile       Ends the document. Causes a newPage, sends the ESCAPEDOC escape call, and deletes
                the printer device context.

FlushPrn        Sends the FLUSHOUTPUT escape code, which flushes the printer's output buffer.

GetPrinterParms        Retrieves the printer parameters from the WIN.INI file.  The syntax for the call
                to GetProfileString is:

                GetProfileString(appName,keyName,default,RetunString: pChar; Size: Integer)

                where appName is the heading name to search for in the WIN.INI file, keyName is the
                key to search for under the heading, default is the default value if keyName is not found,
                ReturnString is the buffer in which the value of KeyName will be stored, and Size is the
                size of the buffer.  The appName is usually 'windows', the keyName is usually 'device'.

                       On returning from the call, ReturnString contains the name of the printer, the
                name of the printer driver and the port to which the printer is connected.  These values
                are separated by commas.  The returned values are copied to instance variables, since
                they are used by other methods in the object.

                       Finally, there is another call to GetProfileString, this time searching for the
                keyName, 'spooler'. The value at this location is then used to set the boolean variable,
                noSpooler to true or false.  This variable indicates whether the print spooler is active.

Init            Constructor method.  Calls the parent (tObject) constructor.

InitAbortProc   Sends the SETABORTPROC escape code to initialize the abort procedure.  The address
                for this procedure is passed in the procAddr variable.  This illustrates the use of the
                InData data structure to send information to Windows.  See the discussion about abort
                procedures, above, for more information.

okPrint         Returns true if the device context is greater than zero.

PrinterPort     Returns the value of the prnPort instance variable.

prnDeviceMode          This method displays the printer device driver dialog box, allowing the user to
                change the printer settings.  This method has several variables:

                       dHandle         Handle of the load library for the current printer.
                       drvName         File name of the driver used to get dHandle.
                       pAddr           address of the procedure in the device DLL that will be called.

                       A call to GetPrinterParms initializes the variables device and driver.  Using the
                value in driver, a filename for the device driver is created by concatenating the extension
                '.drv' to the driver name.  This is stored in the local variable, drvName.  The call to
                LoadLibrary loads the device driver into memory, and returns a tHandle value that
                specifies the library module instance.  If the value is less than 32, an error occurred.
                Note that in this version of the printer object, I am not trapping errors resulting from this
                call.  The first call to GetProcAddress searches the DLL for a function named
                ExtDeviceMode.  If that function is located, a tFarProc value is returned, representing
                the address of the function in the DLL.  This function is present only in device drivers
                written for windows 3.0.  If an address is returned, the ExtDeviceMode function is
                called, using the tGetExtDevMode function type as a template.  The syntax for a call to
                ExtDeviceMode is:

                       ExtDevMode(hWnd,hDriver,lpDevModeOutput,lpDeviceName,
                                       lpPort,lpDevModeInput,lpProfile,wMode)

                where hWnd is the parent window of the caller, hDriver is the device driver module,
                lpDevModeOutput is a tDevMode data structure.  The driver will write the initialization
                information supplied in the lpDevModeInput parameter to this structure. lpDeviceName
                is the name of the printer device, lpPort is the port to which the printer is connected,
                lpDevModeInput is a tDevMode structure that supplies initialization information to the
                printer driver, lpProfile contains the name of a file with initialization information.  If this
                parameter is nil, WIN.INI is used.  wMode is a mask that determines what types of
                operations the function will perform.  If wMode is 0, the call to the function returns the
                number of bytes required by the printer device driver structure. Otherwise, this parameter
                must have one or more of the following values (multiple values should be OR'd
                together):

                       dm_Copy         Writes the printer driver settings to the tDevMode record passed
                                       in lpDevModeOutput.

                       dm_Modify       Modifies the printer driver settings to the values passed in the
                                       lpDevModeInput record.

                       dm_Prompt       Displays the device mode dialog box, and changes the printer
                                       settings to what the user specified

                       dm_Update       Updates the printer environment and the WIN.INI to reflect the
                                       changes made by the user to the printer settings.

                       If you do not include dm_update in the call to DevMode, any changes made to
                the printer settings will be for the current session only, and will not affect other,
                concurrent sessions.

                       If the value returned from the first call to GetProcAddress is nil, indicating that
                the driver was not written for Windows 3, a second call is made to GetProcAddress to
                get the address of the DeviceMode function.  The DeviceMode function always updates
                the WIN.INI file when it's parameters are changed.  The syntax for a call to DeviceMode
                is:
                               DeviceMode()
                where


                       The call to FreeLibrary releases the loaded library module, and any memory
                associated with it.

PrnError        Calls an error routine based on the value of msgNum.  Each of the error routines has
                been coded separately to allow them to be overridden in descendant objects.  The error
                routines are not listed here.  Each one calls the messageBox routine, passing the address
                of the appropriate error string and dialog title.  These strings are declared as constants
                (eMsg) at the start of the implementation section.


USING TPRNDEVICE

        The tPrnDevice object is a formal object; that is, you should never create an instance of it.  It's
purpose is to manage the lower level interface between Windows, an application, and the device driver.
The tPrinter object, discussed next should be instantiated instead.  It provides the higher level interface
between the application and the tPrnDevice object.



THE TPRINTER OBJECT

Instance Variables
HInst           Contains the application instance value passed from the calling application.  This variable
                is used in the NewAbortProc method when the call to MakeProcInstance is made.  See
                the discussion concerning abort procedures at the beginning of this document.

LpAbortProc     Receives the tFarProc value returned from the MakeProcInstance call in the
                NewAbortProc method.

maxX            Holds the maximum line length, in pixels.  This variable is initialized in the Start
                method.

maxY            Holds the maximum page length, in pixels. This variable is initialized in the Start
                method.

Metrics         A tTextMetrics data structure.  This structure contains information about the selected
                font.  It include the average dimensions of the characters, the number of characters in the
                font and the character set on which the font is based. Text metrics are most often used
                to determine the line spacing of the printed output.  In this unit, the height of a line is
                returned by the height method. The height is the sum of the tmHeight field, which is the
                height of each character cell, and the tmExternalLeading fields, which is the
                recommended spacing between the bottom of one character cell and the top of the next.

OkToPrint       This variable is used as a flag to determine whether various steps in the initialization
                process were completed successfully.

posX            Holds the horizontal position of the print head on a line, in pixels.

posY            Holds the vertical position  of the print head on the page, in pixels.

TheParent       A pWindowsObject that is initialized in the Init method.  This variable holds the parent
                window from which this routine was instantiated.  It's value is used in the printDialog
                method to instantiate the print cancel dialog.

TYPES

tPrinter        The printer object.  This is the lowest-level object that should be instantiated to print
                under Windows.  It is a descendant of the tPrnDevice object, which handles the lower
                level interface with Windows.

tPrnDialog      A descendant of tDialog.  This is the print cancel dialog that appears when a print job
                is being spooled.  Pressing the cancel button sets the unit variable UserAbort to true,
                causing the print job to be canceled.


UNIT VARIABLES

PrintDialog     A pointer to a tPrnDialog.  This variable is not an instance variable, since it must be
                accessible from the abortProc function.  Since the AbortProc method has no 'knowledge'
                of the printer object, it would not be able to intercept a message from the dialog.

UserAbort       A global boolean variable that is set when the user presses cancel in the print dialog box.
                This variable is checked by the AbortProc function to see if the print job has been
                aborted.  See the discussion of the Abort Procedure near the beginning of this document.


UNIT METHODS

AbortProc       This function is a callback function, called by windows during a print job.  If the user
                presses cancel in the Print Dialog box, this function notifies Windows that the print job
                had been canceled.


TPRINTER METHODS

CheckNewPage           This method compares the value of posY (the vertical position of the print head
                on the page) with MaxY (the maximum page length).  If posY > maxY, the newPage
                method is called.

CheckStart      This method is responsible for some of the initialization that takes place within the printer
                object.  It's calls deal mainly with the interface between the application and the printer
                object.  The initialization between the printer object and Windows is handled by the Start
                method.  CheckStart is responsible for instantiating the print dialog and the abort
                procedure, and disabling mouse and keyboard input to the parent window.

                       If these initializations are performed successfully, CheckStart then calls the
                beginDoc method, which sends the STARTDOC escape call to the GDI.  If any of the
                Init calls fail, or if the document is not started, checkStart reverses those initializations
                that were successfully completed.

DoNewFrame      Calls the ancestor.doNewFrame method to force a form feed.

Finish          This method is called at the end of a print job.  It calls the EndOfFile method and the
                stopPrinter method, and frees the procedure instance created for the abort procedure.

Height          Returns the line spacing for the selected font.  This is the sum of the metrics.tmHeight
                and metrics.tmExternalLeading fields.  See the discussion under metrics, above, for more
                information.

Init            The Init method calls the ancestor.Init method, and initializes several instance variables.

LineWidth       This method returns the width (line length) of the passed string, based on the currently
                selected font.  This is done through a call to GetTextExtent, which returns a longInt
                value containing the height of the string in the high word, and the width of the string in
                the low word.  The lineWidth method returns only the width of the string.  This value
                is used in the print method to check if the length of the string currently being printed
                causes the current line length to exceed the width of the page.  If so, the offending text
                is wrapped to the next line.

NewAbortProc    This method calls the makeProcInstance function to obtain a far pointer to an abort
                procedure,  bound to the data segment of the current application instance.  This value is
                then passed in the inData parameter of the SetAbortProc escape call.  This function
                returns true if the escape call returns a value greater than zero.

                       It is important to note that all this method does is pass a pointer to a function.
                It does not guarantee that the pointer is valid, or that the function itself is valid.  For
                example, if the EXPORT statement is left off of the AbortProc declaration, the program
                will still run, but the cancel dialog box will not work.

NewLine         NewLine causes a line feed by setting the posX variable to 0, and incrementing the posY
                variable by the value returned by the height method.

NewPage         NewPage starts a new page by resetting the values of posX and posY, and calling the
                doNewFrame method.

PageSize        This method returns a tPoint type containing the size of the page in pixels.  These values
                are obtained by two calls to the Windows GetDeviceCaps method.  GetDeviceCaps
                allows you to determine the extent of the printer device text writing abilities.  There are
                about 28 different queries that can be made, including the horizontal and vertical
                resolution (used here), the aspect ratios for line drawing, the number of fonts, and so on.
                The possible parameters for calls to this method are listed in the Window reference
                guide, under Device capabilities.

Print           This method calls the printString method to send a line of text to the printer.  Before
                making this call, Print determines whether the line length has been exceeded, based on
                the current position of the print head and the width of the string to be printed.  If the
                length has been exceeded, Print forces a new line.  Note that the entire string is wrapped
                to the next line  from the beginning.  The string is then sent to the printer by a call to
                the printString method.  If the printString call is successful, the value of posX is
                incremented by the width of the string.  Under normal circumstances, print does not issue
                a line feed.  The Print method is similar to the Write procedure in standard pascal, in
                that it does not advance to the next line.

PrintDlg        Creates the print dialog box, a modeless dialog present while the print job is in progress.
                The purpose of the dialog box is to allow the user to cancel a print job.

PrintLine       PrintLine is similar to the WriteLn procedure in standard Pascal. It prints a line of text,
                followed by a line feed.  It does this by calling the print method, followed by the
                newLine method.

PrintString     PrintString sends a null-terminated string of text to the selected device context using the
                TextOut method.  The TextOut method writes the character string using the currently
                selected font.  It is called by the Print method.

RemoveDlg       Destroys the print dialog box and disposes of the printDialog pointer.

ResetPos        Sets the posX and posY values to 0, indicating the start of a new page.

Start           The start method takes care of initializing the printer object and its relation with
                Windows.  It is responsible for obtaining a device context, initializing most of the
                instance variables, and calling the CheckStart method to complete the initialization.  If
                checkStart is successful, Start returns true.

StopPrinter     This method re-enables the parent window, removes the print dialog box, and sets the
                OkToPrint variable to false.

TextHeight      Returns the value of the metrics.tmHeight field, which is the height of the character cell
                of the currently selected font.

TextWidth       Returns the average width of the characters in the currently selected character set.

Using the tPrinter object
        The tPrinter object is the object to use in an application to obtain basic access to the printer.  The
sample program TestPrn1 illustrates a simple file printing program that uses this object.  Tprinter handles
the interface between an application and the tPrnDevice object.  That object handles the interface between
the tPrinter object and the GDI.  By maintaining this separation, it becomes much easier to extend the
functionality of either the tPrnDevice or the tPrinter.  If you find that the two objects meet your basic
printing needs, but you need more features than they offer, the correct way to add new features is to
create descendant objects.  You should avoid, as much as possible, modification of these parent objects.


===============================================
                                            SAMPLE PROGRAMS
The TestPrn1 sample program
        This program allows you to print a file or display the device mode dialog for a printer.  The
application object is tTestApp, the main window object is tPrnWindow.  The printer object is instantiated
using the tPrnWindow instance variable aPrinter.  The two methods that interest us are the setPrinter
method and the filePrint method.

SETPRINTER METHOD

        This method displays the device mode dialog.  It consists of three lines:
                aPrinter := new(pPrinter,Init(hInstance,@self));
                aPrinter^.prnDeviceMode(hWindow);
                dispose(aPrinter,Done);

        The first line instantiates aPrinter as a printer object.  The hInstance variable contains the current
tTestApp instance. The @Self parameter is the tPrnWindow object.  The second line calls the
prnDeviceMode method of the printer object.  The hWindow parameter contains the device context for
the current tPrnWind. The third disposes of the printer object. In the printer object, the device mode call
has been set to change the environment only for the current session.


THE FILEPRINT METHOD

        The filePrint method first displays a dialog box to get the name of a file to print.  If the file name
is invalid, the method does nothing. (After all, this is to demonstrate printing!).  Once a valid file name
is received, we are ready to print.  As in the SetPrinter method, an instance of the tPrinter object is
created by the line
                aPrinter := new(pPrinter, Init(hInstance, @self)
        here, the hInstance represents the current instance of tTestApp. @self represent the tPrnWindow
instantiated by tTestApp.  The value of these two parameters will be used in the instantiation of the
AbortProc method and the print dialog box.  The next line calls the Start method:
                if aPrinter^.Start('PrnTest',hWindow) then ...
        here, 'PrnTst' is the document name that will be used to uniquely identify this document, and
hWindow is the current device context (tPrnWindow).  This function call must return true in order for
printing to commence.  If it returns false, an error message should display, indicating what problem
occurred.

        Once the document has been started, the application can send continuous output to the printer.
This is represented by the WHILE..DO loop, following the call to the Start method.  This loop reads in
the next line of text from the file, and calls the printLine method, passing a pointer to the string as a
parameter.

        When the end of textFile has been reached, the Finish method is called to end the print job.  This
call results in the print buffer being flushed, and a NewFrame call to advance the page.  Finally, the
aPrinter variable is disposed, and the job is done.

        While the print job is in progress, you should notice several things.  First, the parent window to
which the print dialog belongs has been disabled.  Mouse and keyboard input to that window have been
inhibited.  It is still possible to access other windows on the screen, but the only active portion of the
print process is the cancel dialog box.  Another thing to notice is that the printing does not start
immediatly.  In fact, for smaller files, printing won't start until you have returned to the application.
This is because Windows and the print manager spool the output to disk or memory, prior to starting
output.  Finally, note that any changes you make to the printer parameters affect only the current print
session (if the driver was written for Windows 3).


                                       THE REPORTPRINTER OBJECT

        The reportPrinter object descends from the tPrinter object.  It does not modify any of tPrinter's
methods.  Rather, it adds some behaviors to tPrinter to change the physical appearance of a printed
document.  ReportPrinter adds user defined pagination, based on lines per page, and headings that are
printed on the top of each page.  In the full implementation of this object in another system, it also
printed column headings, and a columnar report with totals.

        The point of the reportPrinter object is to illustrate how the behavior of an object is modified by
a descendant.  It is intended as an example, not a full implementation of an application.


                                            TREPORTPRINTER

INSTANCE VARIABLES

Heading1        Holds the first heading line.
Heading2        Holds the second heading line.
lineCount       Tracks how many lines have been printed.  This variable is used to determine when to
                advance to a new page.  Note that, in this implementation, if a line is wrapped by the
                Print method, line count is not affected.
maxLines        Maximum number of lines per page.  This variable is set in the Init method.
pageCount       Keeps track of the page number.  This count is included in heading line 2.
rDateTime       Holds the run date and time of the report.  This value is included in heading line 2.


METHODS

Init            Calls the ancestor(tPrinter) Init method to set the application instance and parent values.
                Init then initializes several other of the reportPrinter instance variables.

SetDefaults     SetDefaults initializes the values of the two heading lines.  Heading1 is set to the value
                of the passed parameter, heading2 is set to the run date and time by a call to
                setHeading2.

SetHeading2     Initializes heading2 to the run date and time instance variable and the constant PAGE.

SetPageNum      Strings the current page count into the local variable pCount, then copies it into the
                proper position in heading2.

printMainHeadings      Calls setPageNum, then sends heading1 and heading2 to the printer.

StartNewPage    Page break.  If the page is greater than zero, calls new page, then prints the headings.
                NewPage causes a form feed.  In this version of the object, pageCount is initially set to
                zero.  This routine does not issue a form feed for the first page. (I was running out of
                paper!)

OutText         Check lineCount against maxLines to see if it is time for a new page.  If so,
                startNewPage is called.  The text passed as a parameter is sent to the printer with the
                tPrinter.PrintLine method, and pageNum in incremented by 1.

SetRunTime      A method to get the current date and time, format them, and copy them to the rDateTime
                instance variable.


                                        SAMPLE PROGRAM TESTPRN2
        This application is an example of the use of the reportPrinter object.  The majority of the code
is identical to that in TestPrn1, so I will not repeat that discussion.  One difference is that the
tPrnWindow instance variable aPrinter is now declared to be of type reportPrinter.  The other differences
are in the instantiation of aPrinter in the body of the program, and the object methods that are called
during execution.

                In the method filePrint, the init call for aPrinter now includes an addition parameter, that
for the lines per page.  This value sets the reportPrinter instance variable maxLines, which is checked
each time the outText method is called.  Next, the reportPrinter method setDefaults is called to initialize
the headings.  The default heading passes is simply the word heading.  If a nil value is passes, an empty
string will be printer for heading1.  The second heading line will be the run date and time, and the page
number.  The start method is called to begin the document.  As the file is read, text is sent to the
reportPrinter method outText, rather that the printLine method as was done in the previous example.
This is so reportPrinter can manage the lines per page.  The balance of the execution is identical to the
testPrn1 program.


                                         WINDOWS PRINTING TIPS
        Keep in mind that tPrinter handles text on a line basis; that is, an application sends ready to print
lines to the print or printLine methods.  Remember that these are printer objects.  Their only purpose is
to get information from the application to the printer.  If the output must be formatted in a special
manner, it should be done before the print or printLine methods are called.  That is the technique used
in the original implementation of reportPrinter.  The reportPrinter object formatted the text in to columns,
formatted the subtotals and totals received from other objects, and passed a complete line of text to the
tPrinter object.  The overriding reason for doing this is that you know for certain that if an error in
formatting text occurs, it occurs before the line gets to the printer unit.  It makes report creation and
debugging infinitely easier.  Remember also that object-oriented programming takes the black box concept
several steps farther.  Any object descended from the printer object should concern itself only with
printing.  Any tasks not required for formatting a line, or printing it out do not belong in a printer object.

ENDIT
        I sincerely hope that these objects, examples and documentation prove useful to your quest for
the perfect Windows application.  I have learned a great deal about Windows programming while creating
them.  I look forward to corresponding with you on the Compuserve forum.  Happy Computing!
-Bob Galivan